% File tex-mma-j.tex -- LaTeX documentation of TeX/Mathematica
% Written 2/18/1991 by Dan Dill dan@chem.bu.edu


% Copyright (C) 1991 Dan Dill
% This is part of TeX/Mathematica
%
% TeX/Mathematica is distributed in the hope that it will be useful, but
% WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility to
% anyone for the consequences of using it or for whether it serves any
% particular purpose or works at all, unless he says so in writing.
%
% Permission is granted for use and non-profit distribution of this file
% providing that this notice be clearly maintained, but the right to
% distribute this file for profit or as part of any commercial product is
% specifically reserved for the author.  The same permission and reservation
% applies to the formatted document produced from this file.
%
% Please do not change this file.


\documentstyle[mathematica,psfig]{article}

% Local macros
\def\Mma{{\sl Math\-e\-ma\-ti\-ca}}
\def\TMma{\TeX/\Mma}
\def\bslash{\symbol{'134}}
\newenvironment{ftntsz}{\par\footnotesize}{}

\begin{document}
\psfiginit

\date{February 28, 1991}

\title{Interactive \TMma\ documents\thanks{An article based on this report
will be published in {\sl The Mathematica Journal}.}}
	
\author{Dan Dill\\
	Chemistry Department, Boston University\\
	Boston MA 02215
}

\maketitle

\begin{abstract}
Tools are presented that provide facilities of \Mma\ Notebooks in a UNIX
environment and permit the full use of \TeX\ in their annotation.  With these
\TMma\ tools one can interactively develop and refine teaching and research
documents. The interactive nature of the tools encourages \Mma-based
exploration as a natural part of the writing process.
\end{abstract}


\section{Introduction}

The \Mma\ notebook front end available on Macintosh, NeXT and IBM personal
computers is an exciting step toward the goal of interactive mathematical
documents.

Unfortunately, the notebook front end is not yet available under X windows and
so access to \Mma\ is more cumbersome on UNIX systems than on personal
computers.  This limitation is particularly significant for students, who may
be new to computers and certainly to \Mma.  Indeed, a significant part of the
ready acceptance of \Mma\ by students is its very welcoming, easy to use
notebook front end.

Further, while Notebooks allow annotation of \Mma\ sessions, these annotations
do not support \TeX\ and so full mathematical notation cannot be easily used
to describe \Mma-based explorations.  This restricts the effective use of
\Mma\ in the development of course materials in upper level mathematics
courses and in courses at all levels in astronomy, chemistry, physics and in
all fields of engineering, since mathematics is central to their exposition.

The tools described here were developed to provide some of the facilities of
notebooks in a UNIX environment and to permit the full use of \TeX\ in their
annotation.  The primary tool is the GNU Emacs package {\tt
tex-mathematica} for interactive exchange between a \TeX\ document and \Mma.
However, {\tt tex-mathematica} is independent of \TeX\ and so interactive
\Mma\ documents can be prepared without having to use \TeX.  This is
especially appropriate for students, who should not be expected to have to
learn \TeX\ to use \Mma.  Their teachers, however, may well want to use \TeX\
and macro packages are provided to format \Mma\ text.  It is hoped that
students (and others), when they see what beautiful documents can be created
in this way, will be encouraged to use \TeX\ in their work with \Mma\ too.


\section{Using {\tt tex-mathematica}}

To create an interactive \TMma\ document, use the command {\tt M-x
tex-mathematica}.  This will set up {\tt TeX/Mathematica mode} in the working
buffer and startup \Mma\ as a shell process in {\tt Mathematica mode}
\cite{Jacobson}
in a second buffer.  The command {\tt C-c o} switches to the \Mma\ buffer in
another window.

At the simplest level, all text separated by blank lines is sent to the \Mma\
buffer with the command {\tt C-c RET}.  This command is convenient for
quickly sketching ideas.  However, the bulk of the {\tt tex-mathematica} depends on
its `cell' structure.

\Mma\ code in a \TeX\ document is contained in ``active cells'' delineated by
\begin{ftntsz}\begin{verbatim}
	\begin{mathematica}
	...
	\end{mathematica}
\end{verbatim}\end{ftntsz}
The command {\tt C-c c} creates an active cell and the commands {\tt C-c C-[}
and {\tt C-c C-]} move to preceding and subsequent cells.  Cell input is sent
to \Mma\ with the command {\tt ESC RET} and the output of the last \Mma\
command is inserted into the cell with the command {\tt C-c r} (replace).
These two operations, send and replace, are combined with the command {\tt C-c
u} (update).  For example, here is a \Mma\ cell containing just input:
\begin{mathematica}
Apply[Plus, Array[{{#,#^3},{#^2,1}}&, 100]] // MatrixForm
\end{mathematica}
The enclosing rules delineate cells in the \TeX-formatted document.  Here is
the cell after {\tt C-c u} (update):
\begin{mathematica}
Apply[Plus, Array[{{#,#^3},{#^2,1}}&, 100]] // MatrixForm

		    5050      25502500
		     
Out[1]//MatrixForm= 338350    100
\end{mathematica}
The output is separated from the input by a blank line, and contains the
output marker {\tt Out[$\dots$}, if any.

An important feature of \Mma\ notebook frontends is the ability to specify
that certain active cells should be evaluated as initialization, typically
when a document is first opened.  Such ``initialization cells'' are specified in
\TMma\ documents as
\begin{ftntsz}\begin{verbatim}
	\begin{mathematica}[* Initialization Cell *]
	...
	\end{mathematica}
\end{verbatim}\end{ftntsz}
The command {\tt C-c TAB} toggles the initialization indicator.  The commands
{\tt C-c i} and {\tt C-u C-c i} evaluate all initialization cells in a
document; the first form lets an initialization cell be bypassed optionally.
An initialization cell is marked with \mmabox{I}\ at the right edge of the
cell start rule,
\begin{mathematica}[* Initialization Cell *]
u[t_] := {{Cos[t], -Sin[t]}, {Sin[t], Cos[t]}}; \
v = {{0,I}, {-I,0}};
\end{mathematica}
Note that these particular commands generate no \Mma\ output and so there is
no output portion to the cell.

\Mma\ text may be set off with {\tt TAB} characters; these are reflected
in the formatted document based on an eight-character tab width.  Cell input
can contain more than one \Mma\ statement and each statement can extend over
several lines.  Multiple statements must be separated by `{\tt ;}' and when a
given statement extends over several lines, any lines that could be
interpreted by \Mma\ as a valid (but premature) end of statement must end with
the continuation character `{\tt\bslash}'.  The `{\tt ;}' and `{\tt\bslash}'
are necessary because each line of input is sent separately to \Mma.  For
example, consider the cell
\begin{mathematica}
y = u[Pi] . v \
	/. 0 -> x

Out[3]= {{x, -I}, {I, x}}
\end{mathematica}
Without the `{\tt\bslash}', \Mma\ would process the first line as a complete
statement and then report an error for the next line.

David Jacobson's GNU Emacs package {\tt math}
\cite{Jacobson}
contains several aids that have been made available in the \TeX\ buffer:
automatic syntax checking of \Mma\ input, normal and extended help on \Mma\
symbols ({\tt C-h e} and {\tt C-h E}), name completion ({\tt ESC TAB}), and
location of syntax errors in {\tt .m} files ({\tt C-c C-e}).  In particular,
the input syntax checking detects the problem in the above cell caused by
omitting the `{\tt\bslash}'.  Since {\tt tex-mathematica} uses {\tt
Mathematica mode}, the help, name completion and {\tt .m}-file syntax error
location commands also work directly from the \Mma\ buffer.

Note that {\tt tex-mathematica} and {\tt math} are complimentary approaches to
interacting with \Mma.  With {\tt tex-mathematica} the emphasis is on
interactive document preparation and so editing can be done in the \TMma\
buffer.  With {\tt math} the emphasis is on the \Mma\ session itself and so
one interacts directly with \Mma\ in the \Mma\ buffer.  Because {\tt
tex-mathematica} uses {\tt math}, both approaches can be used as appropriate.

A full on-line description of the facilities of \TMma, using the GNU Emacs
Info documentation browsing system, is given by the command {\tt C-c h}.  A
summary of the commands available in the \TMma\ and \Mma\ buffers is given by
the command {\tt C-h m} when in each buffer.  The version of \TMma\ that is
running is displayed with the command {\tt C-c v}.

\section{\TeX/\LaTeX\ documents}

One reason for creating this package was so that students would be able to
edit, annotate and save their work with \Mma.  This is totally independent of
the use of \TeX. The cell creation, send, update and replace commands
described here, and the help and syntax error facilities, work irrespective of
what typesetting tool, if any, is used for text.  For convenience, however, we
will assume that the text buffer uses \TeX.

Macros are provided for formatting of \Mma\ cells by \TeX.  In 10-point \TeX\
documents the way to input these macros is with
\begin{ftntsz}\begin{verbatim}
	\input mathematica10pt
\end{verbatim}\end{ftntsz}
Use {\tt mathematica12pt} for 12 point \TeX\ documents.  In \LaTeX\ use
\begin{ftntsz}\begin{verbatim}
	\documentstyle[mathematica,...
\end{verbatim}\end{ftntsz}
for both 10 and 12 point documents.  With these macro packages \Mma\ sessions
can be neatly integrated into \TeX\ documents.  The following paragraph, taken
from lecture notes on quantum mechanics, illustrates how \TeX\ and \Mma\ can
be combined.

\def\ket#1{\raise .25ex\hbox{$|$} #1\raise .25ex\hbox{$\rangle$}}
\def\braket#1#2%
{\raise .25ex\hbox{$\langle$} #1 \raise .25ex\hbox{$|$}
	 #2 \raise .25ex\hbox{$\rangle$}}

Clebsch-Gordan coefficients $\braket{j_1 m_1, j_2 m_2}{j m}$ arise in the
quantum theory of angular momentum.  They are elements of unitary
transformation between uncoupled and coupled representations $\ket{j_1 m_1 j_2
m_2}$ and $\ket{j_1 j_2 j m}$.  The unitarity of the transformation implies
the sum rules
\begin{eqnarray*}
\sum_{jm}
	\braket{j_1 m_1, j_2 m_2}{j m}
	\braket{j m}{j_1 m_1, j_2 m_2}
		&=& 1, \\
\sum_{jm}
	\braket{j m}{j_1 m_1, j_2 m_2}
	\braket{j_1 m_1, j_2 m_2}{j m}
		&=& 1.
\end{eqnarray*}
The first of these rules can be illustrated explicitly as follows.  First,
\begin{mathematica}[* Initialization Cell *]
<<DiscreteMath/ClebschGordan.m
\end{mathematica}
defines the function
\verb|Clebsch[{j1,m1},{j2,m2},{j,m}]|.%
\footnote{%
Determining the argument list of {\tt Clebsch} is an example of the
convenience of the help facility.  It was gotten by using {\tt C-h e} and then
pasting in the text displayed in the {\tt *Help*} buffer.} Next, to keep
things simple, consider the case $j_1 = j_2 = l$, so that $0 \le j \le 2l$,
and $m_1 = m_2 = 0$, so that $m = 0$. Then the only coefficients needed are
\begin{mathematica}
cg[l_, j_] := Clebsch[{l,0},{l,0},{j,0}]
\end{mathematica}
and the first sum rule can be written 
\begin{mathematica}
check[l_] := 1 == Sum[cg[l,j]^2, {j, 0, 2 l}]
\end{mathematica}
The rule for $l = 0$ to $l = 5$ is then checked with
\begin{mathematica}
Table[check[i], {i, 0, 5}]

Out[7]= {True, True, True, True, True, True}
\end{mathematica}
The second sum rule can be tested in a similar way.

Using \TMma\ in this way, one can interactively develop and refine course and
research documents.  The interactive nature of these tools encourages
exploration as a natural part of the writing process.  At every point a fully
annotated record of the journey so far is at hand.


\section{\Mma\ graphics}

Graphics generated by \Mma\ can be incorporated into \TeX\ documents using
Trevor Darrell's {\tt psfig} \TeX/\LaTeX\ macros \cite{Darrell}.  These are
described fully in the detailed documentation provided as part of the {\tt
psfig} kit. (The {\tt epsf} macros of Tomas Rokicki's program {\tt dvips}
\cite{Rokicki} can be used instead.)  Including graphics in a \TMma\ document
is a three-part process.  First the {\tt psfig} macro must be read in and
initialized, then graphics are generated to files with appropriate PostScript
bounding box information, and finally files are placed in the document.

Before \Mma\ graphics files can be included in a \TeX\ document, the {\tt psfig}
macro must be set up.  For a \TeX\ document use
\begin{ftntsz}\begin{verbatim}
	\input psfig
	...
	\psfiginit
\end{verbatim}\end{ftntsz}
For a \LaTeX\ document use
\begin{ftntsz}\begin{verbatim}
	\documentstyle[mathematica,psfig,...
	...
	\begin{document}
	...
	\psfiginit
\end{verbatim}\end{ftntsz}
The command {\tt\bslash psfiginit} must come before any use of {\tt\bslash
psfig} (see below); in \LaTeX\ documents {\tt\bslash psfiginit} also must come
after {\tt\bslash begin\{document\}}.

Figures are incorporated via PostScript graphics files that contain the proper
bounding box information.  The \Mma\ command {\tt PSTeX[-graphics-, "file"]},
defined in {\tt PSTeX.m}, generates these graphics files.  If {\tt PSTeX.m}
has not yet been read in (say by the \Mma\ initialization file {\tt init.m}),
it can be loaded with
\begin{mathematica}[* Initialization Cell *]
<<PSTeX.m
\end{mathematica}
To save space, {\tt PSTeX} does not include in the file the PostScript prolog
containing \Mma-specific definitions.  This means that this prolog file must
be downloaded to the printer before the file can be printed.  This is done by
the {\tt dvips} processor, using {\tt\bslash special} commands inserted in the
{\tt .dvi} file by {\tt\bslash psfiginit}.

The figure is scaled to a height equal to {\tt PSTeXHeight} points ($72$
points equal 1 inch), using a scheme developed by Cameron Smith \cite{Smith};
the default height is $100$ points.  After the figure has been stored, the
height can still be changed setting the {\tt height} variable of {\tt\bslash
psfig}.  However, if the height is determined by {\tt PSTeXHeight}, the font
size for labels is 7 points (or whatever the value of the variable {\tt
PSTeXFontsize} is); if the height is determined by the {\tt height} variable,
the whole figure is scaled, including the fonts.

Notice that a file generated by {\tt PSTeX} generally should not be printed
directly, because it does not incorporate the PostScript prolog file, because
the figure is scaled in the way described above, and because the bounding box
adjustment shifts the figure to the lower left corner of the page.  The
command {\tt PSFile}, defined in {\tt PSFile.m}, produces a graphic in a file,
centered and scaled to fill the whole page.

The following example shows how to generate a figure to a file:
\begin{mathematica}
fig = Plot[Sin[x]^3, {x, 0, 4Pi}]; \
	PSTeXFontsize = 9; \
	PSTeX[fig, "sin3x"]; 
\end{mathematica}
Use {\tt ESC ` "} ({\tt M-x quoted-insert "}) to insert a double quote in a
\TeX\ buffer.  Notice that the suffix {\tt .ps} is added automatically to the
file name, and that the font size was changed from the default (7 points).

Finally, the figure can be placed in a \LaTeX\ document with commands like
\begin{ftntsz}\begin{verbatim}
	\begin{figure}
	\centerline{\psfig{figure=sin3x.ps}}
	\caption{{\sl Mathematica} plot of $\sin^3 x$.}
	\end{figure}
\end{verbatim}\end{ftntsz}
which produce the figure seen here.
\begin{figure}
	\centerline{\psfig{figure=sin3x.ps}}
	\caption{\Mma\ plot of $\sin^3 x$.}
\end{figure}
A macro is provided with \TMma\ to place figures in a \TeX\ document in a
similar way.

\section{Getting \TMma}

The \TMma\ tools are available from Internet host {\tt chem.bu.edu} [{\tt
128.197.30.18}] by anonymous {\tt ftp} in directory {\tt
/pub/tex-mathematica}.  The file {\tt README} there describes what to do.  I
can be reached at Internet address {\tt dan@chem.bu.edu}.

\section{Acknowledgment}

I am grateful to Cameron Smith for providing me with the details of his scheme
to adjust the bounding box in \Mma\ graphics for use with {\tt psfig/\TeX}.

\bibliographystyle{unsrt}
\bibliography{tex-mma-j}

%\input{../bio}

\end{document}

% Local Variables:
% eval: (set-variable (quote TeX-directory) default-directory)
% End:
